<!DOCTYPE html>
<html lang="en">
<head>
<title>NC.js REST API Documentation</title>

<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="../css/bootstrap.min.css">
<link rel="stylesheet" href="../css/custom.css">
</head>

<body>

<div class="container">
<nav class="navbar">
<a class="btn btn-info btn-xs navbar-btn pull-right" href="../index.html">Back to Docs</a>
</nav>


<h1 id="api-endpoints">NC.js REST API Documentation</h1>



<h2>REST Endpoints</h2>

<p>The current version of the REST API is v3, and all endpoints can
currently be found grouped under the <code>/v3/nc/</code> path.  The
main concepts are as below:

<ul>
<li><a href="nc/geometry.html"><code>/v3/nc/geometry</code> - Shell geometry used by the machining process</a></li>
<li><a href="nc/id.html"><code>/v3/nc/id</code> - Find EID number from UUID</a></li>
<li><a href="nc/project.html"><code>/v3/nc/project</code> - Name for the machining process</a></li>
<li><a href="nc/state.html"><code>/v3/nc/state</code> - Material removal state for the machining process</a></li>
<li><a href="nc/workplan.html"><code>/v3/nc/workplan</code> - Machining process, workplans and individual operations</a></li>

<li><a href="nc/setup.html"><code>/v3/nc/setup</code> - ID of enclosing workplan with setup transform</a></li>

<li><a href="nc/tolerances.html"><code>/v3/nc/tolerances</code> - Tolerances applied to the digital thread model</a></li>

<li><a href="nc/tool.html"><code>/v3/nc/tool</code> - Test if tool is enabled</a></li>

<li><a href="nc/tools.html"><code>/v3/nc/tools</code> - Find all tools or tool used by a workingstep</a></li>

<li><a href="nc/workpieces.html"><code>/v3/nc/workpieces</code> - Basic information about all workpieces in the digital thread model</a></li>
</ul>
<p>These API endpoints return JSON objects describing
<a href="nc/geometry_object.html">3D geometry</a> and
<a href="nc/state_object.html">simulation state</a>,
<a href="nc/workplan_object.html">machining process</a>,
<a href="nc/workpiece_object.html">workpieces</a>,
<a href="nc/tolerance_object.html">tolerances</a>, and 
<a href="nc/tool_object.html">cutting tools</a>.</p>

<p>Custom Apps may need new endpoints for value-added operations.
These should be placed under <code>/v3/custom</code> to keep them
separate from the baseline endpoints.</p>


<H2 id="events">Server Events</H2>

<p>At startup, the client opens a websocket on the server and listens
for notifications.  The server emits the following notifications

<ul>
<li><code id="delta">nc:delta</code> - Issued when the machine tool
position changes or material removal occurs.  The argument is
a <a href="nc/state_object.html#delta">delta state object</a>

<li><code id="feed">nc:feed</code> - Issued every time the
machine tool feedrate changes.  The argument is the numeric value of
the new feed.

<li><code id="mtc">nc:mtc</code>  (MTstate.js)
<li><code id="probe">nc:probe</code>
<li><code id="qifLoad">nc:qifLoad</code> - Issued when a QIF file is
loaded and applied to the tolerances in the digital thread model.  See
the <a href="nc/tolerances.html#qifload">qif load endpoint</a> for
discussion.</li>

<li><code id="speed">nc:speed</code> - Issued whenever the simulation
speed slider is changed.  The argument is the new numeric value for
the speed factor.  See the <a href="nc/state.html#loop">state loop
endpoint</a> for more information.</li>

<li><code id="spindle">nc:spindle</code> - Issued every time the
machine tool spindle speed changes.  The argument is the numeric value
of the new spindle speed.  Defined in state.js.

<li><code id="state">nc:state</code> - Issued whenever the simulation
loop starts or stops.  the argument is the string "play" when the loop
has started, and "pause" when the loop has stopped.
</ul>


<H2>Server / Client Communication</H2>

<p>Upon inital connection to the server, the server will send the
packaged client javascript to the browser.  This client will then
establishes a websocket connection back to the server to listen for
the server events described above.

<p>The first action of the client is to GET /v3/nc/state/key, and
receive a <a href="state_object.html#key">key state object</a> that
describes the initial position of everything in the digital thread
model.  The client will parse the key state and executes the
ApplyDelta logic described below.
(<a href="https://github.com/steptools/NC.js/blob/master/src/client/models/data_loader.js">Code in data_loader.js</a></p>

<p>Whenever the tool moves, the server will send
an <code>nc:delta</code> event over the websocket, with
a <a href="state_object.html#delta">delta state object</a> that
describes the new dynamic shell and the positions of everything.  The
client will parse the delta state and executes the ApplyDelta logic
described below. <a href="https://github.com/steptools/NC.js/blob/master/src/client/models/cad_manager.js#L151">Code in cad_manager.js</a></p>

<p>Other events are occasionally generated, and the client responds by
updating the responsive view with new feed rates, spindle speeds,
speed slider position, play/pause button, etc.


<H3>Client ApplyDelta logic</H3>

<p>On receipt of a KeyState or DeltaState, the client invokes
the <a href="https://github.com/steptools/NC.js/blob/master/src/client/models/nc.js#L221">applyDelta function in nc.js</a></p>

<ol>
<li>Hide any geometry currently displayed</li>
<li>Call the <a href="https://github.com/steptools/NC.js/blob/NewDeltas/src/client/models/nc.js#L265">dynamicShell handler</a>, which attempts to update the dynamic shell if necessary (if newversion &gt; currentversion).</li>
<li>Display any requested geometry which is in our local cache</li>
<li>Queue geometry loads from server for geometry which is not in local cache</li>
</ol>

</div>

<script src="../js/jquery.min.js"></script>
<script src="../js/bootstrap.min.js"></script>
</body>
</html>
